VARPTR, VARSEG Functions

 Action

 Return the address of a variable or string descriptor.

 Syntax


  VARPTR( variablename)

  VARSEG( variablename)


 Remarks

 The argument  variablename can be any BASIC variable, including a record
 variable or record element.

  VARPTR and  VARSEG return the address of a variable (for numeric variables)
 or the address of a string descriptor (for string variables) as indicated in
 the following table.

-----------------------------------------------------------------------------
 For a variable of type.  VARSEG returns.          VARPTR returns.
 ----------------------------------------------------------------------------
 Numeric                  Segment address of       Offset address of
                          variable                 variable

 String                   Segment address of       Offset address of string
                          string  descriptor       descriptor (near strings)
                          (near strings)

 Name not previously      Segment address of new   Offset address of new
 defined                  variable ( VARSEG also   variable ( VARPTR also
                          creates the new          creates the  new
                          variable)                variable)





 When  variablename is a numeric variable, the  VARPTR function returns an
 unsigned integer (the offset of the variable within its segment). When
 variablename is a numeric variable, the  VARSEG function returns an unsigned
 integer (the segment address of the variable). When  variablename is a
 near-string variable,  VARSEG and  VARPTR return a string-descriptor address
 that contains the length of the string and the address at which it is
 stored.

 If  variablename is not defined before  VARPTR or  VARSEG is called, the
 variable is created and its address is returned.

  VARPTR and  VARSEG are often used with  Absolute,  BLOAD,  BSAVE,
 Interrupt,  PEEK,  POKE, or when passing arrays to procedures written in
 other languages. When using  VARPTR or  VARSEG to get the address of an
 array, use the first element of the array as the argument.

 DIM A(150)

 .

 .

 .

 ArrAddress=VARPTR(A(1))

 You can use  VARPTR alone to get the address of a variable stored in DGROUP.
 You must use both  VARPTR and  VARSEG to get the complete address of a
 variable stored in far memory.



 When programming with OS-2 protected mode, the  VARSEG function returns the
 selector of the specified variable or array.



 Note


 Because many BASIC statements move variables in memory, use the values
 returned by  VARPTR and  VARSEG immediately after the functions are used.


 It is not meaningful to use  VARSEG and  VARPTR for far strings, since the
 format of the far strings' string descriptor is different from the string
 descriptor for near strings. See the entry for  StringAddress for
 information on locating the address of a far string's string descriptor. See
 the entries for  SSEG,  SADD, and  SSEGADD for information on locating the
 segment and offset addresses of far strings.


 You can no longer use  VARPTR to get the address of a file's buffer. Use the
  FILEATTR function to get information about a file.


 Programs written in earlier versions of BASIC that used  VARPTR to access
 numeric arrays may no longer work. You must now use a combination of  VARPTR
 and  VARSEG. For example, the following QuickBASIC Version 3.0 fragment no
 longer works correctly.

 DIM Cube(675)

 .

 .

 .

 BSAVE "graph.dat",VARPTR(Cube(1)),2700

 The fragment could be rewritten as follows to work with the current version
 of BASIC.


 DIM Cube(675)

 .

 .

 .

 ' Change segment to segment containing Cube.

 DEF SEG=VARSEG(Cube(1))

 BSAVE "graph.dat",VARPTR(Cube(1)),2700

 DEF SEG' Restore BASIC segment.

 The  VARSEG function, combined with  VARPTR, replaces the PTR86 subprogram
 used in previous versions of BASIC.


 VARPTR and VARSEG and Expanded Memory Arrays

 Do not pass expanded memory arrays to non-BASIC procedures. If you start QBX
 with the -Ea switch, any of these arrays may be stored in expanded memory.

   -   Numeric arrays less than 16K in size.

   -   Fixed-length string arrays less than 16K in size.

   -   User-defined-type arrays less than 16K in size.




 If you want to pass expanded memory arrays to non-BASIC procedures, first
 start QBX without the -Ea switch. (Without the -Ea switch, no arrays are
 stored in expanded memory.)


 For more information on using expanded memory, see "Memory Management for
 QBX" in  Getting Started.

 See Also

  DEF SEG,  PEEK,  POKE,  SADD,  VARPTR$

 Example

 The following example illustrates how to use the  VARPTR and  VARSEG
 functions in a  CALL statement to pass a BASIC array to a C routine.

 DEFINT A-Z
 DECLARE SUB AddArr CDECL (BYVAL Offs, BYVAL Segm, BYVAL Num)
 DIM A(1 TO 100) AS INTEGER
 ' Fill the array with the numbers 1 to 15.
 FOR I = 1 TO 15
    A(I) = I
 NEXT I
 '
 ' Call the C function. AddArr expects a far address (segment
 ' and offset). Because CDECL puts things on the stack from
 ' right to left, put the offset ( VARPTR(A(1)) ) first in the
 ' list, followed by the segment ( VARSEG(A(1)) ).
 '
 CALL AddArr(VARPTR(A(1)), VARSEG(A(1)), 15)
 '
 ' Print the modified array.
 FOR I = 1 TO 15
    PRINT A(I)
 NEXT I
 END

 This C routine increments values of a BASIC array. It must be compiled and
 the .OBJ file linked to the BASIC code above.

 -* Add one to the first num elements of array arr.*-
 void far addarr(arr,num)
 int far *arr;
 int num;
 {
    int i;
    for(i=0;i<num;i++) arr[i]++;
 }